docs: add cleanup command documentation and update spec status by UserAd · Pull Request #33 · UserAd/AgentMail

UserAd · 2026-01-18T04:31:04Z

Summary

Add comprehensive cleanup command documentation to README.md with usage examples, flags, and output format
Add "Cleanup utility" to the Features list in README.md
Update specs/011-cleanup/spec.md status from Draft to Implemented after verifying all 23 functional requirements
Add reminder to CLAUDE.md about updating README after spec implementation

Test plan

Verify README.md cleanup documentation renders correctly
Verify spec status is updated to Implemented
Verify CLAUDE.md reminder is present in Specification Workflow section

Summary by CodeRabbit

New Features
- Cleanup command to remove offline recipients, stale recipients, old delivered messages, and empty mailboxes.
Documentation
- Full Cleanup utility docs: command syntax, flags (--stale-hours, --delivered-hours, --dry-run), examples, sample output, and exit codes.
- Updated README with formatting adjustments, added server tool reference, and a cautionary note to update README after implementing specs.
Style
- Added markdown linting configuration for consistent docs formatting.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

- Add cleanup command documentation to README.md with full usage examples - Add cleanup utility to Features list in README.md - Update specs/011-cleanup/spec.md status from Draft to Implemented - Add reminder to CLAUDE.md about updating README after spec implementation

coderabbitai · 2026-01-18T04:34:10Z

📝 Walkthrough

Walkthrough

The pull request updates project documentation: adds Cleanup utility documentation to README.md, marks the cleanup spec as Implemented, adds a .markdownlint.json file, and inserts cautionary reminders in CLAUDE.md to update README.md after implementing specs. No code or behavioral changes.

Changes

Cohort / File(s)	Summary
Cleanup feature & README `README.md`	Adds documentation for a new Cleanup CLI command (what it cleans, flags `--stale-hours`, `--delivered-hours`, `--dry-run`), usage examples, sample output, and exit codes; formatting and example block adjustments across related command docs.
Specification status & notes `specs/011-cleanup/spec.md`, `CLAUDE.md`	Updates cleanup spec status from Draft to Implemented; inserts cautionary notes in `CLAUDE.md` reminding to update `README.md` after implementing specs.
Linting config `.markdownlint.json`	Adds Markdown lint configuration (disables MD013; sets MD024 `sibling_only=true`).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: adding cleanup command documentation to README.md and updating the spec status to Implemented.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📜 Recent review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8df0eb1 and 78a7202.

📒 Files selected for processing (2)

.markdownlint.json
README.md

🧰 Additional context used

🧠 Learnings (9)

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: AgentMail must run inside a tmux session and interact with tmux windows using recipient names

Applied to files:

README.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*.go : Must pass go vet static analysis with no errors

Applied to files:

README.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*.go : Code must pass gosec security analysis with no reported issues

Applied to files:

README.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*.go : Code must be formatted according to gofmt standards

Applied to files:

README.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*.go : Code must pass govulncheck vulnerability scanning

Applied to files:

README.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to go.mod : Dependencies must pass go mod verify checks

Applied to files:

README.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*.go : Project requires Go 1.21 or higher (currently using Go 1.25.5 per ic-001 constitution)

Applied to files:

README.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*_test.go : All tests must pass with -race flag and achieve >= 80% code coverage

Applied to files:

README.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*.go : Message storage must use JSONL format in .agentmail/ directory hierarchy

Applied to files:

README.md

🔇 Additional comments (5)

.markdownlint.json (1)

1-6: LGTM! Sensible markdownlint configuration.

Disabling MD013 (line length) is appropriate for documentation with long URLs and code examples. Setting MD024 siblings_only: true allows repeated heading names (e.g., "Examples", "Exit codes") under different parent sections, which matches the README's command documentation structure.

README.md (4)

23-23: LGTM! Feature list updated correctly.

The cleanup utility feature is now properly listed among the Features, consistent with the new documentation section added below.

280-328: LGTM! Comprehensive cleanup command documentation.

The documentation follows the established pattern of other commands with clear sections for syntax, behavior, flags with defaults, examples, output format, and exit codes. The note at line 328 appropriately clarifies this is an administrative command not exposed via MCP tools.

The markdown formatting issues flagged in previous reviews (blank lines around code blocks, language specifiers) have been addressed.

597-614: LGTM! Section renamed to fix duplicate heading.

Renaming from "How It Works" to "Architecture" resolves the MD024 duplicate heading issue while remaining semantically appropriate for the ASCII diagram showing component relationships.

361-367: LGTM! Table formatting standardized.

The table separator alignment is now consistent across all tables in the document (here and at lines 491, 568, 577).

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@README.md`:
- Around line 292-299: Add a blank line before the code fence following the
"**Output:**" heading and change the fence from ``` to ```text so the block is
separated and uses a language identifier; locate the output example block (the
triple-backtick block showing "Cleanup complete: Recipients removed..." after
the "**Output:**" line and ensure there is an empty line before the fence and
the fence is ```text rather than ``` to fix markdown formatting and
highlighting.
- Around line 281-291: Add a blank line immediately before the fenced code block
that begins with "```bash" (the block containing "agentmail cleanup --dry-run",
"agentmail cleanup", and the "--stale-hours" example) so the markdown renders
correctly; update the README.md by inserting one empty line above that code
fence.

📜 Review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a593976 and 8df0eb1.

📒 Files selected for processing (3)

CLAUDE.md
README.md
specs/011-cleanup/spec.md

🧰 Additional context used

🧠 Learnings (5)

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Feature specifications should be stored in .specify/templates/ directory

Applied to files:

CLAUDE.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Project constitution and architectural decisions are documented in .specify/memory/constitution.md

Applied to files:

CLAUDE.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*.go : Message storage must use JSONL format in .agentmail/ directory hierarchy

Applied to files:

CLAUDE.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*.go : Implementation must use only Go standard library (per IC-001), specifically os/exec for tmux, encoding/json for JSONL, bufio, os, fmt, io, time, sync, syscall, filepath, and os/signal as needed

Applied to files:

CLAUDE.md

📚 Learning: 2026-01-18T04:25:38.976Z

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-18T04:25:38.976Z
Learning: Applies to **/*.go : Project requires Go 1.21 or higher (currently using Go 1.25.5 per ic-001 constitution)

Applied to files:

CLAUDE.md

🪛 markdownlint-cli2 (0.18.1)

README.md

281-281: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

293-293: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

293-293: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (3)

README.md (1)

23-23: Excellent documentation for the cleanup command!

The cleanup command documentation is comprehensive, well-structured, and follows the same format as other commands in the README. It clearly explains:

What gets cleaned (4 categories)

Available flags with defaults

Usage examples including dry-run

Sample output format

Exit codes

Administrative scope note

This makes the feature easily discoverable and usable.

Also applies to: 261-304

CLAUDE.md (1)

81-82: Excellent process reminder!

This is a valuable addition to the development workflow. It helps ensure that user-facing documentation stays in sync with implemented features, preventing the common issue of outdated README files.

specs/011-cleanup/spec.md (1)

5-5: The cleanup command implementation is already present in the codebase. The PR includes not only documentation but also the complete implementation in internal/cli/cleanup.go (221 lines) with all four cleanup phases: offline recipients, stale recipients, old messages, and empty mailboxes. All required mail package functions exist, and the command is properly integrated into the CLI while correctly excluded from both onboard and MCP interfaces.

Likely an incorrect or invalid review comment.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

README.md

- Add .markdownlint.json config to disable MD013 (line length) rule - Add blank lines around lists and fenced code blocks (MD031, MD032) - Add language specifiers to code blocks (MD040) - Fix table column spacing (MD060) - Fix link fragment to match actual heading (MD051) - Rename duplicate "How It Works" heading to "Architecture" (MD024)

coderabbitai bot reviewed Jan 18, 2026

View reviewed changes

README.md Show resolved Hide resolved

README.md Show resolved Hide resolved

UserAd merged commit 6c1eb33 into main Jan 18, 2026
3 checks passed

UserAd deleted the docs-update branch January 18, 2026 04:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add cleanup command documentation and update spec status#33

docs: add cleanup command documentation and update spec status#33
UserAd merged 2 commits intomainfrom
docs-update

UserAd commented Jan 18, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Jan 18, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

UserAd commented Jan 18, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

UserAd commented Jan 18, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Jan 18, 2026 •

edited

Loading